<!DOCTYPE HTML>
<html lang="en">
<head>
<title>StrGet() - Syntax &amp; Usage | AutoHotkey</title>
<meta name="description" content="The StrGet function copies a string from a memory address, optionally converting it from a given code page." />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<link href="../static/theme.css" rel="stylesheet" type="text/css" />
<script src="../static/content.js" type="text/javascript"></script>
</head>
<body>

<h1>StrGet() <span class="ver">[AHK_L 46+]</span></h1>

<p>Copies a string from a memory address, optionally converting it from a given code page.</p>

<pre class="Syntax">String := <span class="func">StrGet</span>(Source <span class="optional">, Length</span> <span class="optional">, Encoding := <i>None</i></span>)</pre>
<h2>Parameters</h2>
<dl>

  <dt>Source</dt>
  <dd>
    <p>The memory address of the string.</p>
    <p>The string is not required to be <a href="../Concepts.htm#null-termination">null-terminated</a> if the <em>Length</em> parameter is specified.</p>
  </dd>

  <dt>Length</dt>
  <dd>
    <p>The length of the string, in <a href="../Concepts.htm#character">characters</a>. This can be omitted if the string is <a href="../Concepts.htm#null-termination">null-terminated</a>.</p>
    <p class="warning"><strong>Note:</strong> Omitting <em>Length</em> when the string is not null-terminated may cause an access violation which terminates the program, or some other undesired result. Specifying an incorrect length may produce unexpected behaviour.</p>
    <p class="warning"><strong>Note:</strong> Embedded null characters are unsupported and will generally cause truncation of the string.</p>
  </dd>

  <dt>Encoding</dt>
  <dd>
    <p>The source encoding; for example, <code>"UTF-8"</code>, <code>"UTF-16"</code> or <code>"CP936"</code>. For numeric identifiers, the prefix "CP" can be omitted only if <em>Length</em> is specified. Specify an empty string or <code>"CP0"</code> to use the system default ANSI code page.</p>
  </dd>

</dl>

<h2>Return Value</h2>
<p>This function returns the copied or converted string. If the source encoding was specified correctly, the return value always uses the <a href="../Concepts.htm#string-encoding">native encoding</a>. It is always <a href="../Concepts.htm#null-termination">null-terminated</a>, but the null-terminator is not included in the return value's <a href="StringLen.htm">length</a>.</p>

<h2>Error Handling</h2>
<p>An empty string is returned if invalid parameters are detected, or if the conversion cannot be performed.</p>

<h2>Remarks</h2>
<p>Note that the return value is always in the <a href="../Concepts.htm#string-encoding">native encoding</a> of the current executable, whereas <i>Encoding</i> specifies how to interpret the string read from the given <i>Source</i>. If no <em>Encoding</em> is specified, the string is simply copied without any conversion taking place.</p>
<p class="note">In other words, StrGet is used to retrieve text from a memory address, or convert it to a format the script can understand.</p>
<p>If conversion between code pages is necessary, the length of the return value may differ from the length of the source string.</p>

<h2>Related</h2>
<p><a href="../Concepts.htm#string-encoding">String Encoding</a>, <a href="StrPut.htm">StrPut()</a>, <a href="../Compat.htm">Script Compatibility</a>, <a href="FileEncoding.htm">FileEncoding</a>, <a href="DllCall.htm">DllCall()</a>, <a href="VarSetCapacity.htm">VarSetCapacity()</a></p>

<h2>Examples</h2>
<div class="ex" id="ExNumEnc">
<p><a href="#ExNumEnc">#1</a>: Either <em>Length</em> or <em>Encoding</em> may be specified directly after <em>Source</em>, but in those cases <em>Encoding</em> must be non-numeric:</p>
<pre>
str := StrGet(address, "cp0")  <em>; Code page 0, unspecified length</em>
str := StrGet(address, n, 0)   <em>; Maximum n chars, code page 0</em>
str := StrGet(address, 0)      <em>; Maximum 0 chars (always blank)</em>
</pre>
</div>

</body>
</html>
